3 * Advanced generator of database load balancing objects for database farms.
5 * This program is free software; you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation; either version 2 of the License, or
8 * (at your option) any later version.
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
15 * You should have received a copy of the GNU General Public License along
16 * with this program; if not, write to the Free Software Foundation, Inc.,
17 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
18 * http://www.gnu.org/copyleft/gpl.html
24 namespace Wikimedia\Rdbms
;
26 use InvalidArgumentException
;
29 * A multi-database, multi-master factory for Wikimedia and similar installations.
30 * Ignores the old configuration globals.
34 class LBFactoryMulti
extends LBFactory
{
35 /** @var array A map of database names to section names */
36 private $sectionsByDB;
39 * @var array A 2-d map. For each section, gives a map of server names to
42 private $sectionLoads;
45 * @var array[] Server info associative array
46 * @note The host, hostName and load entries will be overridden
48 private $serverTemplate;
52 /** @var array A 3-d map giving server load ratios for each section and group */
53 private $groupLoadsBySection = [];
55 /** @var array A 3-d map giving server load ratios by DB name */
56 private $groupLoadsByDB = [];
58 /** @var array A map of hostname to IP address */
59 private $hostsByName = [];
61 /** @var array A map of external storage cluster name to server load map */
62 private $externalLoads = [];
65 * @var array A set of server info keys overriding serverTemplate for
68 private $externalTemplateOverrides;
71 * @var array A 2-d map overriding serverTemplate and
72 * externalTemplateOverrides on a server-by-server basis. Applies to both
73 * core and external storage
75 private $templateOverridesByServer;
77 /** @var array A 2-d map overriding the server info by section */
78 private $templateOverridesBySection;
80 /** @var array A 2-d map overriding the server info by external storage cluster */
81 private $templateOverridesByCluster;
83 /** @var array An override array for all master servers */
84 private $masterTemplateOverrides;
87 * @var array|bool A map of section name to read-only message. Missing or
88 * false for read/write
90 private $readOnlyBySection = [];
92 /** @var array Load balancer factory configuration */
95 /** @var LoadBalancer[] */
96 private $mainLBs = [];
98 /** @var LoadBalancer[] */
102 private $loadMonitorClass = 'LoadMonitor';
108 private $lastSection;
111 private $maxLag = self
::MAX_LAG_DEFAULT
;
113 /** @var int Default 'maxLag' when unspecified */
114 const MAX_LAG_DEFAULT
= 10;
117 * @see LBFactory::__construct()
119 * Template override precedence (highest => lowest):
120 * - templateOverridesByServer
121 * - masterTemplateOverrides
122 * - templateOverridesBySection/templateOverridesByCluster
123 * - externalTemplateOverrides
125 * Overrides only work on top level keys (so nested values will not be merged).
127 * Server configuration maps should be of the format Database::factory() requires.
128 * Additionally, a 'max lag' key should also be set on server maps, indicating how stale the
129 * data can be before the load balancer tries to avoid using it. The map can have 'is static'
130 * set to disable blocking replication sync checks (intended for archive servers with
133 * @param array $conf Parameters of LBFactory::__construct() as well as:
134 * - sectionsByDB Map of database names to section names.
135 * - sectionLoads 2-d map. For each section, gives a map of server names to
136 * load ratios. For example:
143 * - serverTemplate Server configuration map intended for Database::factory().
144 * Note that "host", "hostName" and "load" entries will be
145 * overridden by "sectionLoads" and "hostsByName".
146 * - groupLoadsBySection 3-d map giving server load ratios for each section/group.
156 * - groupLoadsByDB 3-d map giving server load ratios by DB name.
157 * - hostsByName Map of hostname to IP address.
158 * - externalLoads Map of external storage cluster name to server load map.
159 * - externalTemplateOverrides Set of server configuration maps overriding
160 * "serverTemplate" for external storage.
161 * - templateOverridesByServer 2-d map overriding "serverTemplate" and
162 * "externalTemplateOverrides" on a server-by-server basis.
163 * Applies to both core and external storage.
164 * - templateOverridesBySection 2-d map overriding the server configuration maps by section.
165 * - templateOverridesByCluster 2-d map overriding the server configuration maps by external
167 * - masterTemplateOverrides Server configuration map overrides for all master servers.
168 * - loadMonitorClass Name of the LoadMonitor class to always use.
169 * - maxLag Avoid replica DBs with more lag than this many seconds.
170 * - readOnlyBySection A map of section name to read-only message.
171 * Missing or false for read/write.
173 public function __construct( array $conf ) {
174 parent
::__construct( $conf );
177 $required = [ 'sectionsByDB', 'sectionLoads', 'serverTemplate' ];
178 $optional = [ 'groupLoadsBySection', 'groupLoadsByDB', 'hostsByName',
179 'externalLoads', 'externalTemplateOverrides', 'templateOverridesByServer',
180 'templateOverridesByCluster', 'templateOverridesBySection', 'masterTemplateOverrides',
181 'readOnlyBySection', 'maxLag', 'loadMonitorClass' ];
183 foreach ( $required as $key ) {
184 if ( !isset( $conf[$key] ) ) {
185 throw new InvalidArgumentException( __CLASS__
. ": $key is required." );
187 $this->$key = $conf[$key];
190 foreach ( $optional as $key ) {
191 if ( isset( $conf[$key] ) ) {
192 $this->$key = $conf[$key];
198 * @param bool|string $domain
201 private function getSectionForDomain( $domain = false ) {
202 if ( $this->lastDomain
=== $domain ) {
203 return $this->lastSection
;
205 list( $dbName, ) = $this->getDBNameAndPrefix( $domain );
206 $section = $this->sectionsByDB
[$dbName] ??
'DEFAULT';
207 $this->lastSection
= $section;
208 $this->lastDomain
= $domain;
214 * @param bool|string $domain
215 * @return LoadBalancer
217 public function newMainLB( $domain = false ) {
218 list( $dbName, ) = $this->getDBNameAndPrefix( $domain );
219 $section = $this->getSectionForDomain( $domain );
220 $groupLoads = $this->groupLoadsByDB
[$dbName] ??
[];
222 if ( isset( $this->groupLoadsBySection
[$section] ) ) {
223 $groupLoads = array_merge_recursive(
224 $groupLoads, $this->groupLoadsBySection
[$section] );
227 $readOnlyReason = $this->readOnlyReason
;
228 // Use the LB-specific read-only reason if everything isn't already read-only
229 if ( $readOnlyReason === false && isset( $this->readOnlyBySection
[$section] ) ) {
230 $readOnlyReason = $this->readOnlyBySection
[$section];
233 $template = $this->serverTemplate
;
234 if ( isset( $this->templateOverridesBySection
[$section] ) ) {
235 $template = $this->templateOverridesBySection
[$section] +
$template;
238 return $this->newLoadBalancer(
240 $this->sectionLoads
[$section],
247 * @param DatabaseDomain|string|bool $domain Domain ID, or false for the current domain
248 * @return LoadBalancer
250 public function getMainLB( $domain = false ) {
251 $section = $this->getSectionForDomain( $domain );
252 if ( !isset( $this->mainLBs
[$section] ) ) {
253 $this->mainLBs
[$section] = $this->newMainLB( $domain );
256 return $this->mainLBs
[$section];
259 public function newExternalLB( $cluster ) {
260 if ( !isset( $this->externalLoads
[$cluster] ) ) {
261 throw new InvalidArgumentException( __METHOD__
. ": Unknown cluster \"$cluster\"" );
263 $template = $this->serverTemplate
;
264 if ( $this->externalTemplateOverrides
) {
265 $template = $this->externalTemplateOverrides +
$template;
267 if ( isset( $this->templateOverridesByCluster
[$cluster] ) ) {
268 $template = $this->templateOverridesByCluster
[$cluster] +
$template;
271 return $this->newLoadBalancer(
273 $this->externalLoads
[$cluster],
275 $this->readOnlyReason
279 public function getExternalLB( $cluster ) {
280 if ( !isset( $this->extLBs
[$cluster] ) ) {
281 $this->extLBs
[$cluster] = $this->newExternalLB( $cluster );
284 return $this->extLBs
[$cluster];
287 public function getAllMainLBs() {
289 foreach ( $this->sectionsByDB
as $db => $section ) {
290 if ( !isset( $lbs[$section] ) ) {
291 $lbs[$section] = $this->getMainLB( $db );
298 public function getAllExternalLBs() {
300 foreach ( $this->externalLoads
as $cluster => $unused ) {
301 $lbs[$cluster] = $this->getExternalLB( $cluster );
308 * Make a new load balancer object based on template and load array
310 * @param array $template
311 * @param array $loads
312 * @param array $groupLoads
313 * @param string|bool $readOnlyReason
314 * @return LoadBalancer
316 private function newLoadBalancer( $template, $loads, $groupLoads, $readOnlyReason ) {
317 $lb = new LoadBalancer( array_merge(
318 $this->baseLoadBalancerParams(),
320 'servers' => $this->makeServerArray( $template, $loads, $groupLoads ),
321 'maxLag' => $this->maxLag
,
322 'loadMonitor' => [ 'class' => $this->loadMonitorClass
],
323 'readOnlyReason' => $readOnlyReason
326 $this->initLoadBalancer( $lb );
332 * Make a server array as expected by LoadBalancer::__construct, using a template and load array
334 * @param array $template
335 * @param array $loads
336 * @param array $groupLoads
339 private function makeServerArray( $template, $loads, $groupLoads ) {
342 $groupLoadsByServer = $this->reindexGroupLoads( $groupLoads );
343 foreach ( $groupLoadsByServer as $server => $stuff ) {
344 if ( !isset( $loads[$server] ) ) {
348 foreach ( $loads as $serverName => $load ) {
349 $serverInfo = $template;
351 $serverInfo['master'] = true;
352 if ( $this->masterTemplateOverrides
) {
353 $serverInfo = $this->masterTemplateOverrides +
$serverInfo;
357 $serverInfo['replica'] = true;
359 if ( isset( $this->templateOverridesByServer
[$serverName] ) ) {
360 $serverInfo = $this->templateOverridesByServer
[$serverName] +
$serverInfo;
362 if ( isset( $groupLoadsByServer[$serverName] ) ) {
363 $serverInfo['groupLoads'] = $groupLoadsByServer[$serverName];
365 $serverInfo['host'] = $this->hostsByName
[$serverName] ??
$serverName;
366 $serverInfo['hostName'] = $serverName;
367 $serverInfo['load'] = $load;
368 $serverInfo +
= [ 'flags' => IDatabase
::DBO_DEFAULT
];
370 $servers[] = $serverInfo;
377 * Take a group load array indexed by group then server, and reindex it by server then group
378 * @param array $groupLoads
381 private function reindexGroupLoads( $groupLoads ) {
383 foreach ( $groupLoads as $group => $loads ) {
384 foreach ( $loads as $server => $load ) {
385 $reindexed[$server][$group] = $load;
393 * @param DatabaseDomain|string|bool $domain Domain ID, or false for the current domain
394 * @return array [database name, table prefix]
396 private function getDBNameAndPrefix( $domain = false ) {
397 $domain = ( $domain === false )
399 : DatabaseDomain
::newFromId( $domain );
401 return [ $domain->getDatabase(), $domain->getTablePrefix() ];
405 * Execute a function for each tracked load balancer
406 * The callback is called with the load balancer as the first parameter,
407 * and $params passed as the subsequent parameters.
408 * @param callable $callback
409 * @param array $params
411 public function forEachLB( $callback, array $params = [] ) {
412 foreach ( $this->mainLBs
as $lb ) {
413 $callback( $lb, ...$params );
415 foreach ( $this->extLBs
as $lb ) {
416 $callback( $lb, ...$params );